feat(integrations): let Google Custom Search use another API address - #557

What and why

google_cse_search and the Google Custom Search connect check always call https://www.googleapis.com/customsearch/v1. Google's overview page says "The Custom Search JSON API is closed to new customers." and "Existing Custom Search JSON API customers have until January 1, 2027 to transition to an alternative solution" (https://developers.google.com/custom-search/v1/overview), so after that date the google_cse search provider fails and there's nothing to change in its setup.

This adds an optional API address setup field to the google_cse integration (required=False, like the optional fields on the IMAP plugin). validate checks the key against that address instead of Google's, refuses anything that isn't http:// or https://, and stores base_url with the key only when it's set. web_search passes it to google_cse_search. Left empty, both calls go to Google exactly as before, and existing connections have no base_url so they don't change. No issue for this one, it's a small optional field.

How I tested it

• New tests/integrations/test_google_cse_address.py (respx, no network): search and connect go to Google without the field, go to the given address with the same key, cx, q and num and never touch Google with it, store base_url only when it's set, and refuse file:///etc/passwd. 6 passed.
• .venv/bin/python -m pytest -q: 3271 passed, 19 skipped.
• .venv/bin/ruff check sentient tests: All checks passed.

Real test

• Setup: engine from this branch (python -m sentient serve --port 8795) with a new empty SENTIENT_HOME and a random gateway token, on a Linux server. It has no system keychain, so I set PYTHON_KEYRING_BACKEND=keyrings.alt.file.PlaintextKeyring inside the test home; without it, connect answers "Your system keychain is unavailable, so the credentials can't be saved safely." A small local HTTP server on 127.0.0.1 stood in for the search API and returned one Custom Search item.
• Model: no model involved.
• POST /api/integrations/google_cse/connect with base_url ftp://x → 400 {"detail":"The API address has to start with http:// or https://."}
• The same with base_url http://127.0.0.1:8932/customsearch/v1 → 200, status: connected. The local server logged GET /customsearch/v1 with cx=c1.
• POST /api/integrations/google_cse/test → 200 {"ok":true,"detail":"Connected."}, and the local server logged a second GET /customsearch/v1, so the stored address came back out of the keychain.
• Not tested: a chat turn where a model calls web_search with search_provider: google_cse (no local model on that machine; the unit tests cover that call), and the connect screen itself, which I didn't build or capture.

Checklist

• Tests added or updated, and pytest / npm run typecheck pass locally for what I touched
• ruff check sentient tests is clean
• docs/API.md updated if the desktop ↔ engine contract changed
• A changelog entry in changes/ (for example changes/123.fixed.md, see changes/README.md) if users will
  notice this change. Don't edit CHANGELOG.md.
• No keys, tokens or personal data in the code, tests or screenshots

I run a search API that answers in the Custom Search JSON format, which is how I ran into the date.

Summary by CodeRabbit

• New Features
  • Google Custom Search can use an optional compatible API address. Without one, searches continue to use Google.
  • The configured address is used for connection checks and searches, while preserving existing query parameters.
• Bug Fixes
  • Address validation accepts only HTTP or HTTPS addresses; a blank address is treated as unset.
  • Custom addresses must return a JSON object. Connection failures and invalid responses are reported as integration errors.